Adding @phpstan-assert-if-true would be a nice addition here:

Static analysis with PHPStan would then satisfied in cases like this when attempting to iterate over $data:

Otherwise, PHPStan here is typing $data as mixed:

phpstan: Argument of an invalid type mixed supplied for foreach, only iterables are supported.

Otherwise, if this were just an implementation of array_is_list() then it could do:

@phpstan-assert-if-true list<mixed> $data

But it seems perhaps unsafe to assume that every case of wp_is_numeric_array() being used to today intends array_is_list().

@phpstan-assert-if-true array<int, mixed> $data

I have not seen this, but I guess it’s tantamount to guard functions in TypeScript? seeing as how it’s already in place elsewhere I’ll add it, though I am curious about whether you have concern about basing the types on the trust of docblock comments vs. inferences.

In TypeScript projects I’ve been skeptical of this due to the loss of constraints and soundness. It does provide good autocomplete, and a function like this should be relatively easy to ensure the constraints…

it seems perhaps unsafe to assume that every case of wp_is_numeric_array() being used to today intends array_is_list().

yeah I think so. I didn’t have confidence in my assumption about it, but I knew that changing the behavior would invite breakage. 🙃

I have not seen this, but I guess it’s tantamount to guard functions in TypeScript? seeing as how it’s already in place elsewhere I’ll add it, though I am curious about whether you have concern about basing the types on the trust of docblock comments vs. inferences.

It's a good point. I'm not sure why PHPStan doesn't just infer what will be returned by looking at the executed code. I inquired of Claude:

Good question — and the short answer is that PHPStan deliberately doesn't do this for user-defined functions, regardless of how analyzable the body is.

PHPStan treats function calls as black boxes

When you call wp_is_numeric_array( $x ), PHPStan only knows the declared return type: bool. It does not re-analyze the function body at each call site to figure out what true vs. false implies about the arguments. So at a call site like:

if ( wp_is_numeric_array( $x ) ) {
    // Without the annotation, $x is still `mixed` here.
}

…there is no narrowing at all unless you tell PHPStan the relationship. The @phpstan-assert-if-true annotation is precisely the mechanism for declaring "if this returns true, the argument is array<int, mixed>."

This is by design. Back-propagating "the return was true, therefore argument has shape X" from arbitrary control flow is, in general, undecidable and would be prohibitively expensive to do for every function at every call site. PHPStan only does this kind of inference for:

1. Hardcoded built-ins — is_array(), is_string(), array_is_list() (which narrows to list<...>), etc. These are special-cased in PHPStan's engine. array_is_list is exactly analogous to what we want here, but it gets narrowing only because PHPStan ships explicit knowledge of it. A WordPress function it's never heard of gets nothing.
2. Functions with explicit @phpstan-assert* annotations — the manual opt-in.
3. Custom TypeSpecifyingExtensions — a PHP class you register that programmatically tells PHPStan how to narrow. That's the heavier alternative to the annotation.

Why the body wouldn't be "easy" to invert anyway

Even setting aside the design decision, the narrowing here isn't a simple matter of reading the body. The true result comes from the fall-through path after a loop:

foreach ( $data as $key => $value ) {
    if ( is_string( $key ) ) {
        return false;
    }
}
return true;

To conclude array<int, mixed>, an analyzer would have to reason: "the loop visited every key, none satisfied is_string, array keys are only ever int|string, therefore every key is int." That's universal quantification over a loop combined with exhaustiveness reasoning — exactly the sort of thing static analyzers don't attempt when deriving implications from return values.

So the annotation isn't compensating for a PHPStan weakness so much as supplying knowledge PHPStan never tries to derive on its own for custom functions — the same way @param/@return exist because it can't always infer those either.

One thing worth noting: the annotation is a promise PHPStan trusts but lightly verifies. With @phpstan-assert*, PHPStan does check that the asserted type is compatible with what the body could return, but it won't catch a subtly-wrong assertion. So the correctness of array<int, mixed> here rests on the human reasoning above, not on PHPStan having proven it.